<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
  <meta name="copyright"
 content="Copyright (c) EclipseSource and others 2009, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
  <meta http-equiv="Content-Type"
 content="text/html; charset=ISO-8859-1">
  <meta http-equiv="Content-Style-Type" content="text/css">
  <link REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
  <title>Publishing p2 metadata</title>
</head>
<body>
<h1>Publishing p2 metadata</h1>
<p>
The p2 metadata contains useful information about the elements that can be installed.  These elements
are called Installable Units (IUs).  Among other things, the IUs describe dependencies,
properties and configuration information.
</p>

<p>
There are three different ways p2 repositories can be created.  1) By using the export wizard, 2) using PDE Build, and 3)
using the publisher.  The Plug-in Development Environment Guide explains how the
<a href="../../org.eclipse.pde.doc.user/guide/tools/export_wizards/export_features.htm">feature export wizard</a>,
<a href="../../org.eclipse.pde.doc.user/guide/tools/export_wizards/export_product.htm">product export wizard</a> and
<a href="../../org.eclipse.pde.doc.user/tasks/pde_p2_builds.htm">PDE Build</a>
can be used to generate metadata.  The remainder of this document explains how the publisher can be used.
</p>

<p>
The <em>publisher</em> is the means by which deployable entities get added to repositories. For example,
the publisher can be used to create an IU from an OSGi Bundle or Eclipse Feature.  The publisher consists
of an extensible set of publishing actions, applications and Ant tasks that allow users to generate
p2 repositories from a number of different sources.
</p>

<p>
In order to be backwards-compatible, p2 is able to install things from old-style update sites and extension locations
by generating metadata for these things on-the-fly, but this of course is not the optimal situation. Ideally, plug-in
developers should create p2 metadata when they produce their bundles, features, and products.
</p>

<p>
This document describes how to publish p2 metadata for your software using <b>the publisher</b>.
</p>

<p>
The publisher can be used in two ways:
</p>
<ol>
<li><a href="#headless_applications">Command line applications</a></li>
<li><a href="p2_publishingtasks.htm">Ant Tasks</a></li>
</ol>

<h2><a name="headless_applications">Command Line Applications</a></h2>
<p>
p2 ships with four command line publisher applications that plug-in developers can run. The applications are contained
in <code>org.eclipse.equinox.p2.publisher</code> and <code>org.eclipse.equinox.p2.updatesite</code>.  These bundles are
part of the Eclipse SDK. The four applications are:
</p>

<ol>
<li><a href="#updatesite_publisher">UpdateSite Publisher</a></li>
<li><a href="#features_and_bundles_publisher">Features And Bundles Publisher</a></li>
<li><a href="#product_publisher">Product Publisher</a></li>
<li><a href="#category_publisher">Category Publisher</a></li>
</ol>

<h3><a name="updatesite_publisher">UpdateSite Publisher</a></h3>

<p>
The updatesite publisher application (<code>org.eclipse.equinox.p2.publisher.UpdateSitePublisher</code>) is a command line application
that is capable of generating metadata (p2 repositories) from an update site containing a site.xml, bundles and features.  The
updatesite publisher can be invoked using the generic Eclipse launcher format as follows:
</p>

<p>
<code>eclipse -application org.eclipse.equinox.p2.publisher.UpdateSitePublisher &lt;publisherArgs&gt;</code>
</p>

<p>Here are the supported command-line options:</p>

<dl>
<dt><code>-metadataRepository &lt;URI&gt;</code></dt>
	<dd>the URI to the metadata repository where the installable units should be published</dd>
<dt><code>-artifactRepository &lt;URI&gt;</code></dt>
	<dd>the URI to the artifact repository where the artifacts should be published</dd>
<dt><code>-source &lt;path&gt;</code></dt>
	<dd>the location of the update site</dd>
<dt><code>-compress</code></dt>
	<dd>a flag indicating that the repository should be compressed</dd>
<dt><code>-append</code></dt>
	<dd>flag indicating that repositories will be appended to as opposed to over-written</dd>
<dt><code>-publishArtifacts</code></dt>
	<dd>flag indicating that the artifacts should be published (copied) to the repository. When this flag is not set, the actual bytes
	underlying the artifact will not be copied, but the repository index will be created. When this option is not
	specified, it is recommended to set the artifactRepository to be in the same location as the source (<code>-source</code>).</dd>
</dl>

<p>Here is an example of how the updatesite publisher can be used to create a compressed p2 repository from an update site: </p>
<pre>
eclipse -application org.eclipse.equinox.p2.publisher.UpdateSitePublisher
 -metadataRepository file:/&lt;some location&gt;/repository
 -artifactRepository file:/&lt;some location&gt;/repository
 -source /&lt;location with a site.xml&gt;
 -configs gtk.linux.x86
 -compress
 -publishArtifacts
</pre>

<p>
Once you run the publisher, you will see the generated artifact repository index file in <code>artifacts.xml</code> and
the generated metadata repository index file in the <code>content.xml</code> (or <code>artifacts.jar</code> and
<code>content.jar</code> if you used the -compress option). There is nothing forcing you to have the metadata and
artifact repositories co-located, but you can do this if you wish to.
</p>

<h3><a name="features_and_bundles_publisher">Features And Bundles Publisher</a></h3>

<p>
The features and bundles publisher application (org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher)
is a command line application that is capable of generating metadata (p2 repositories)
from pre-built Eclipse bundles and features. The features and bundle publisher can be invoked using the
generic Eclipse launcher format as follows:
</p>

<p>
<code>eclipse -application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher &lt;publisherArgs&gt;</code>
</p>

<p>Here are command-line options:</p>
<dl>
<dt><code>-metadataRepository &lt;URI&gt;</code></dt>
	<dd>the URI to the metadata repository where the installable units should be published</dd>
<dt><code>-artifactRepository &lt;URI&gt;</code></dt>
	<dd>the URI to the artifact repository where the artifacts should be published</dd>
<dt><code>-source &lt;path&gt;</code></dt>
	<dd>the location of the update site</dd>
<dt><code>-bundles &lt;path&gt;</code></dt>
	<dd>the location of the bundles</dd>
<dt><code>-features &lt;path&gt;</code></dt>
	<dd>the location of the features</dd>
<dt><code>-compress</code></dt>
	<dd>a flag indicating that the repository should be compressed</dd>
<dt><code>-append</code></dt>
	<dd>flag indicating that repositories will be appended to as opposed to over-written</dd>
<dt><code>-publishArtifacts</code></dt>
	<dd>flag indicating that the artifacts should be published (copied) to the repository. When this flag is not set, the actual bytes
	underlying the artifact will not be copied, but the repository index will be created. When this option is not
	specified, it is recommended to set the artifactRepository to be in the same location as the source (<code>-source</code>).</dd>
</dl>

<p>
The features and bundles publisher application can be invoked using the <code>-source</code> option by pointing
at a directory that contains two sub-directories (features and plug-ins).  The publisher can also be invoked
by pointing at the bundles and features separately and using the <code>-bundles</code> and <code>-features</code> options.
</p>

<p>Here is an example of how the features and bundles publisher can be used to create a compressed p2 repository from a collection
of bundles and features: </p>
<pre>
eclipse -application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher
   -metadataRepository file:/&lt;some location&gt;/repository
   -artifactRepository file:/&lt;some location&gt;/repository
   -source /&lt;location with a plugin and feature directory&gt;
   -configs gtk.linux.x86
   -compress
   -publishArtifacts
</pre>

<h3><a name="product_publisher">Product Publisher</a></h3>
<p>
The product publisher application (<code>org.eclipse.equinox.p2.publisher.ProductPublisher</code>) is a command line application
that is capable of generating metadata (p2 repositories) from a .product file.  The product publisher does not generate metadata
for the bundles and features that make up the product.  The product publisher can be invoked using the
generic Eclipse launcher format as follows:
</p>

<p>
<code>eclipse -application org.eclipse.equinox.p2.publisher.ProductPublisher &lt;publisherArgs&gt;</code>
</p>

<p>Here are the supported command-line options:</p>
<dl>
<dt><code>-metadataRepository &lt;URI&gt;</code></dt>
	<dd>the URI to the metadata repository where the installable units should be published</dd>
<dt><code>-artifactRepository &lt;URI&gt;</code></dt>
	<dd>the URI to the artifact repository where the artifacts should be published</dd>
<dt><code>-productFile &lt;path&gt;</code></dt>
	<dd>the location of the product file</dd>
<dt><code>-executables &lt;path&gt;</code></dt>
	<dd>the location of the executables feature</dd>
<dt><code>-flavor &lt;String&gt;</code></dt>
	<dd>the flavor used for the configuration units (if unsure, using tooling)</dd>
<dt><code>-compress</code></dt>
	<dd>a flag indicating that the repository should be compressed</dd>
<dt><code>-append</code></dt>
	<dd>flag indicating that repositories will be appended to as opposed to over-written</dd>
<dt><code>-configs &lt;spec&gt;</code></dt>
	<dd>a set of environment properties for the <tt>os</tt>, <tt>ws</tt> and <tt>arch</tt> parameters of the system which the product supports and can be provisioned on;
	can specify more than one platform in a comma-separated list of such triplets;
	if the product can support any environment, <tt>"-configs ANY"</tt> or <tt>"-configs ANY.ANY.ANY"</tt> should be used.</dd>
</dl>

<p>Here is an example of how the product publisher can be used to create a p2 repository from a .product file:</p>

<pre>
eclipse -application org.eclipse.equinox.p2.publisher.ProductPublisher
   -metadataRepository file:/&lt;some location&gt;/repository
   -artifactRepository file:/&lt;some location&gt;/repository
   -productFile /&lt;location&gt;/&lt;filename&gt;.product
   -append
   -executables /&lt;deltapack parent&gt;/delta/eclipse/features/org.eclipse.equinox.executable_3.3.200.v20090426-1530-7M-Fm-FI3UouOdcoUJz-7oc
   -flavor tooling
   -configs gtk.linux.x86
</pre>

<h3><a name="category_publisher">Category Publisher</a></h3>
<p>
The category publisher application (org.eclipse.equinox.p2.publisher.CategoryPublisher) is a command line application that is capable of
categorizing a set of Installable Units in a given repository. The categorization is driven from a category file. The category publisher
can be invoked using the generic Eclipse launcher format as follows:
</p>

<p>
<code>eclipse -application org.eclipse.equinox.p2.publisher.CategoryPublisher &lt;publisherArgs&gt;</code>
</p>

<p>Here is an example of how the product publisher can be used to categorize a p2 repository from a category.xml file: </p>

<pre>
eclipse -application -application org.eclipse.equinox.p2.publisher.CategoryPublisher
   -metadataRepository file:/&lt;some location&gt;/repository
   -categoryDefinition file:/&lt;some location&gt;/category.xml
   -compress
</pre>
<p>
Categories are always appended to a repository.
</p>

<h2>Updated Documentation</h2>
<p>
Up-to-date information on the p2 publisher can be found on the
<a href="http://wiki.eclipse.org/Equinox/p2/Publisher">Eclipse p2 wiki</a>.
</p>
</body>
</html>